/*
 * Licensed under the MIT License
 * 
 * Copyright (c) 2011 Kay Kreuning
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 * 
 * http://code.google.com/p/hyves-as3-sdk/
 */
package nl.hyves.api.core
{
	import nl.hyves.api.login.ILogin;
	import nl.hyves.api.utils.BatchCall;

	public interface IHyvesAPI
	{
		/**
		 * URL to execute all the API methods against
		 */
		function get endpoint():String;
		
		/**
		 * Consumer registered with this IHyvesAPI instance
		 */
		function get consumer():Consumer;
		
		/**
		 * Accesstoken used by this IHyvesAPI instance
		 */
		function get accesstoken():OAuthToken;
		
		/**
		 * Check to see if this IHyvesAPI instance is logged in or not.
		 * A Vector with API methods can be given to check if this instance is logged in for those specific methods.
		 * 
		 * @param forAPIMethods Vector of API methods
		 * @return true if this instance is logged in, otherwise false
		 */
		function isLoggedIn(forAPIMethods:Vector.<String> = null):Boolean;
		
		/**
		 * Let the user log in autenticate this IHyvesAPI instance.
		 * 
		 * @param method ILogin method used to login
		 * @param callback function to call when the user is authenticated
		 */
		function login(method:ILogin, callback:Function):void;
		
		/**
		 * Clears any existing accesstoken on the IHyvesAPI instance, basically revoking access.
		 */
		function clearAccesstokenCache():void;
		
		/**
		 * Call an API method. Note that this IHyvesAPI instance must be logged in to actually make the call. If the instance is not logged in, calls will be cached and executed when the service is logged in.
		 * 
		 * @param method API method to call, must be an <code>IMethod</code> or a String
		 * @param callback function to call with an <code>IResponse</code> object when the method returns data
		 * @param parameters optional parameters for the given method
		 * @param immediate execute the method immediately and do not check if this IHyvesAPI instance is logged in or not
		 */
		function call(method:*, callback:Function, ...parameters):void;
		
		/**
		 * Upload an image to the Hyves media platform.
		 * 
		 * @param image image to upload, must be a <code>Bitmap</code>, <code>BitmapData</code> or an encoded image in the form of a <code>ByteArray</code>
		 * @param callback function to call with an <code>IResponse</code> object when the upload is complete
		 * @param options optional parameters for the upload, must be an <code>UploadParameters</code> or an Object
		 */
		function upload(image:*, callback:Function, parameters:Object = null):void;
		
		/**
		 * Create a batch, allowing you to make multiple API method calls in one.
		 * 
		 * @return a <code>BatchCall</code> instance
		 */
		function createBatch():BatchCall;
	}
}